package com.googlecode.bip.dao;

import java.io.Serializable;
import java.sql.SQLException;
import java.util.List;
import javax.naming.NamingException;
import com.googlecode.bip.entity.ITopic;
import com.googlecode.bip.entity.IllegalIdLocalException;
import com.googlecode.bip.entity.impl.Local;

/**
 * DAO for {@link ITopic}
 */
public interface TopicDAO extends Serializable
{
    /**
     * Returns an @{link ITopic} according to idtopic and idlocal
     *
     * @param idtopic   idtopic (int value)
     * @param idlocal   idlocal (2 characters String)
     * @return an @{link ITopic} according to idtopic and idlocal
     * @throws NamingException if any
     * @throws SQLException if any
     */
    public ITopic findTopic( int idtopic, String idlocal )
        throws NamingException, SQLException;

    /**
     * Returns an @{link ITopic} according to idtopic and idlocal
     *
     * @param idtopic	idtopic (int value)
     * @param local   	Local object to use
     * @return an @{link ITopic} according to idtopic and local
     * @throws NamingException if any
     * @throws SQLException if any
     */
    public ITopic findTopic( int idtopic, Local local )
        throws NamingException, SQLException;

    /**
     * Returns an {@link ITopic} according to topic name and idlocal
     *
     * @param name      name of topic
     * @param idlocal   Local object to use
     * @return an @{link ITopic} if found, null otherwise
     *
     * @throws NamingException if any
     * @throws SQLException if any
     */
    public ITopic findTopic( String name, String idlocal)
        throws NamingException, SQLException;

    /**
     * Returns a {@link List} of {@link ITopic} according to topic name and idlocal.
     * Returned list must have none or ONLY one element !
     *
     * @param name      name of topic
     * @param idlocal   Local object to use
     * @return Returns a {@link List} of {@link ITopic}
     * @throws NamingException if any
     * @throws SQLException if any
     */
    public List<ITopic> findTopics( String name, String idlocal)
        throws NamingException, SQLException;

    /**
     * Returns all translation for a @{link ITopic}
     *
     * @param idtopic idtopic to find
     * @return a List with translation for the giving idtopic
     * @throws SQLException if any
     * @throws NamingException if any
     */
    public List<ITopic> findTopics( int idtopic )
        throws SQLException, NamingException;


    /**
     * Returns all topics created so far
     *
     * @return A list of topics
     * @throws SQLException if any
     * @throws NamingException if any
     * @see #getRootTopics()
     * @see #getSubTopics(int)
     */
    public List<ITopic> getAllTopics()
        throws SQLException, NamingException;

    /**
     * Returns List of {@link ITopic} with no parent topic.
     * <p>
     * More formally returns all topics that {@link ITopic#getParentIdTopic()} equals
     * to 0 (or NULL)
     * </p>
     *
     * @return List of {@link ITopic} under giving idtopic, list is sorted according to {@link ITopic#getOrder()} value.
     * @throws SQLException if any
     * @throws NamingException if any
     * @see #getSubTopics(int)
     */
    public List<ITopic> getRootTopics()
        throws SQLException, NamingException;

    /**
     * Returns List of {@link ITopic} under giving idtopic.
     * <p>
     * More formally returns all topics that {@link ITopic#getParentIdTopic()} equals
     * to idtopic
     * </p>
     *
     * @param idtopic Parent id topic
     * @return List of {@link ITopic} under giving idtopic, list is sorted according to {@link ITopic#getOrder()} value.
     * @throws SQLException if any
     * @throws NamingException if any
     * @see #getRootTopics()
     */
    public List<ITopic> getSubTopics( int idtopic )
        throws SQLException, NamingException;

    /**
     * Create a new Topic in database (must not exist)
     * <br/>
     * {@link ITopic#getIdTopic()} value is ignored by insertion (must be equal 0)
     * <br/>
     * After database insert this method update {@link ITopic#getIdTopic()} content
     * with the index created by database.
     *
     * @param itopic {@link ITopic} to add in database
     * @return new {@link ITopic} if insert succeed, null otherwise
     * @throws NamingException if any
     * @throws SQLException if any
     * @throws IllegalIdLocalException if idlocal is not valid
     */
    public ITopic insertTopic(
            int     parentIdTopic,
            String  idlocal,
            String  topicName,
            String  topicDescription
            )
        throws NamingException, SQLException, IllegalIdLocalException;

    /**
     * Insert a new translation of {@link ITopic}
     *
     * @param topicBase     Already existing {@link ITopic}
     * @param idlocal       New local for this {@link ITopic}
     * @param name          Name to set
     * @param description   Description to set
     * @return new {@link ITopic} if insert succeed, null otherwise
     * @throws NamingException if any
     * @throws SQLException if any
     * @throws IllegalIdLocalException if idlocal not valid
     */
    public ITopic insertTopic(
            ITopic  topicBase,
            String  idlocal,
            String  name,
            String  description
            )
        throws SQLException, NamingException, IllegalIdLocalException;

    /**
     * Update {@link ITopic}
     *
     * @param itopic {@link ITopic} to update in database
     * @return true if update succeed
     * @throws NamingException if any
     * @throws SQLException if any
     * @throws IllegalIdLocalException if {@link ITopic#getIdLocal()} is not valid
     */
    public boolean updateTopic( final ITopic itopic )
        throws NamingException, SQLException, IllegalIdLocalException;


//    /**
//     * Remove Topic from database, if no more use
//     *
//     * @param topic
//     * @return
//     * @throws NamingException if any
//     * @throws SQLException if any
//     */
//    public boolean deleteTopic( final ITopic topic )
//        throws NamingException, SQLException;

    /**
     * Delete topic support, if no more use.
     * Delete topic support but no translation. You must delete
     * all translation before delete topic support.
     *
     * @param idtopic topic support to delete
     * @return true if 1 line have been deleted.
     * @throws NamingException if any
     * @throws SQLException if any
     * @see #deleteTopicLocal(int, String)
     * @see #deleteTopicLocals(int)
     */
    public boolean deleteTopic( final int idtopic )
        throws NamingException, SQLException;


    /**
     * Remove Topic translation from database
     *
     * @param idtopic topic translation to delete
     * @param idlocal idlocal for this translation
     * @return true if 1 line have been deleted.
     * @throws NamingException if any
     * @throws SQLException if any
     * @see #deleteTopicLocals(int)
     * @see #deleteTopic(int)
     */
    public boolean deleteTopicLocal( int idtopic, String idlocal )
       throws NamingException, SQLException;

    /**
     * Remove all Topic translations from database
     *
     * @param idtopic topic translations to delete
     * @return count of translation deleted.
     * @throws NamingException if any
     * @throws SQLException if any
     * @see #deleteTopicLocal(int, String)
     * @see #deleteTopic(int)
     */
    public int deleteTopicLocals( int idtopic )
       throws NamingException, SQLException;

    /**
     * Increment starting from 0 order field of all {@link ITopic} object
     * found in database.
     *
     * @throws NamingException if any
     * @throws SQLException if any
     */
    public void packOrderTopics()
        throws NamingException, SQLException;

}

